Go Template

Introduction

ApplicationSet is able to use Go Text Template. To activate this feature, add goTemplate: true to your ApplicationSet manifest.

The Sprig function library (except for env, expandenv and getHostByName) is available in addition to the default Go Text Template functions.

An additional normalize function makes any string parameter usable as a valid DNS name by replacing invalid characters with hyphens and truncating at 253 characters. This is useful when making parameters safe for things like Application names.

Another slugify function has been added which, by default, sanitizes and smart truncates (it doesn’t cut a word into 2). This function accepts a couple of arguments:

  • The first argument (if provided) is an integer specifying the maximum length of the slug.
  • The second argument (if provided) is a boolean indicating whether smart truncation is enabled.
  • The last argument (if provided) is the input name that needs to be slugified.

Usage example

  1. apiVersion: argoproj.io/v1alpha1
  2. kind: ApplicationSet
  3. metadata:
  4.   name: test-appset
  5. spec:
  6.   ... 
  7.   template:
  8.     metadata:
  9.       name: 'hellos3-{{.name}}-{{ cat .branch | slugify 23 }}'
  10.       annotations:
  11.         label-1: '{{ cat .branch | slugify }}'
  12.         label-2: '{{ cat .branch | slugify 23 }}'
  13.         label-3: '{{ cat .branch | slugify 50 false }}'

If you want to customize options defined by text/template, you can add the goTemplateOptions: ["opt1", "opt2", ...] key to your ApplicationSet next to goTemplate: true. Note that at the time of writing, there is only one useful option defined, which is missingkey=error.

The recommended setting of goTemplateOptions is ["missingkey=error"], which ensures that if undefined values are looked up by your template then an error is reported instead of being ignored silently. This is not currently the default behavior, for backwards compatibility.

Motivation

Go Template is the Go Standard for string templating. It is also more powerful than fasttemplate (the default templating engine) as it allows doing complex templating logic.

Limitations

Go templates are applied on a per-field basis, and only on string fields. Here are some examples of what is not possible with Go text templates:

  • Templating a boolean field.

    1. apiVersion: argoproj.io/v1alpha1
    2. kind: ApplicationSet
    3. spec:
    4.   goTemplate: true
    5.   goTemplateOptions: ["missingkey=error"]
    6.   template:
    7.     spec:
    8.       source:
    9.         helm:
    10.           useCredentials: "{{.useCredentials}}"  # This field may NOT be templated, because it is a boolean field.

  • Templating an object field:

    1. apiVersion: argoproj.io/v1alpha1
    2. kind: ApplicationSet
    3. spec:
    4.   goTemplate: true
    5.   goTemplateOptions: ["missingkey=error"]
    6.   template:
    7.     spec:
    8.       syncPolicy: "{{.syncPolicy}}"  # This field may NOT be templated, because it is an object field.

  • Using control keywords across fields:

    1. apiVersion: argoproj.io/v1alpha1
    2. kind: ApplicationSet
    3. spec:
    4.   goTemplate: true
    5.   goTemplateOptions: ["missingkey=error"]
    6.   template:
    7.     spec:
    8.       source:
    9.         helm:
    10.           parameters:
    11.           # Each of these fields is evaluated as an independent template, so the first one will fail with an error.
    12.           - name: "{{range .parameters}}"
    13.           - name: "{{.name}}"
    14.             value: "{{.value}}"
    15.           - name: throw-away
    16.             value: "{{end}}"

  • Signature verification is not supported for the templated project field when using the Git generator.

    1. apiVersion: argoproj.io/v1alpha1
    2. kind: ApplicationSet
    3. spec:
    4.   goTemplate: true
    5.   template:
    6.     spec:
    7.       project: {{.project}}

Migration guide

Globals

All your templates must replace parameters with GoTemplate Syntax:

Example: {{ some.value }} becomes {{ .some.value }}

Cluster Generators

By activating Go Templating, {{ .metadata }} becomes an object.

  • {{ metadata.labels.my-label }} becomes {{ index .metadata.labels "my-label" }}
  • {{ metadata.annotations.my/annotation }} becomes {{ index .metadata.annotations "my/annotation" }}

Git Generators

By activating Go Templating, {{ .path }} becomes an object. Therefore, some changes must be made to the Git generators’ templating:

  • {{ path }} becomes {{ .path.path }}
  • {{ path.basename }} becomes {{ .path.basename }}
  • {{ path.basenameNormalized }} becomes {{ .path.basenameNormalized }}
  • {{ path.filename }} becomes {{ .path.filename }}
  • {{ path.filenameNormalized }} becomes {{ .path.filenameNormalized }}
  • {{ path[n] }} becomes {{ index .path.segments n }}
  • {{ values }} if being used in the file generator becomes {{ .values }}

Here is an example:

  1. apiVersion: argoproj.io/v1alpha1
  2. kind: ApplicationSet
  3. metadata:
  4.   name: cluster-addons
  5. spec:
  6.   generators:
  7.   - git:
  8.       repoURL: https://github.com/argoproj/argo-cd.git
  9.       revision: HEAD
  10.       directories:
  11.       - path: applicationset/examples/git-generator-directory/cluster-addons/*
  12.   template:
  13.     metadata:
  14.       name: '{{path.basename}}'
  15.     spec:
  16.       project: default
  17.       source:
  18.         repoURL: https://github.com/argoproj/argo-cd.git
  19.         targetRevision: HEAD
  20.         path: '{{path}}'
  21.       destination:
  22.         server: https://kubernetes.default.svc
  23.         namespace: '{{path.basename}}'

becomes

  1. apiVersion: argoproj.io/v1alpha1
  2. kind: ApplicationSet
  3. metadata:
  4.   name: cluster-addons
  5. spec:
  6.   goTemplate: true
  7.   goTemplateOptions: ["missingkey=error"]
  8.   generators:
  9.   - git:
  10.       repoURL: https://github.com/argoproj/argo-cd.git
  11.       revision: HEAD
  12.       directories:
  13.       - path: applicationset/examples/git-generator-directory/cluster-addons/*
  14.   template:
  15.     metadata:
  16.       name: '{{.path.basename}}'
  17.     spec:
  18.       project: default
  19.       source:
  20.         repoURL: https://github.com/argoproj/argo-cd.git
  21.         targetRevision: HEAD
  22.         path: '{{.path.path}}'
  23.       destination:
  24.         server: https://kubernetes.default.svc
  25.         namespace: '{{.path.basename}}'

It is also possible to use Sprig functions to construct the path variables manually:

with goTemplate: falsewith goTemplate: truewith goTemplate: true + Sprig
{{path}}{{.path.path}}{{.path.path}}
{{path.basename}}{{.path.basename}}{{base .path.path}}
{{path.filename}}{{.path.filename}}{{.path.filename}}
{{path.basenameNormalized}}{{.path.basenameNormalized}}{{normalize .path.path}}
{{path.filenameNormalized}}{{.path.filenameNormalized}}{{normalize .path.filename}}
{{path[N]}}-{{index .path.segments N}}

Available template functions

ApplicationSet controller provides:

  • all sprig Go templates function except env, expandenv and getHostByName

  • normalize: sanitizes the input so that it complies with the following rules:

    1. contains no more than 253 characters
    2. contains only lowercase alphanumeric characters, ‘-‘ or ‘.’
    3. starts and ends with an alphanumeric character

  • slugify: sanitizes like normalize and smart truncates (it doesn’t cut a word into 2) like described in the introduction section.

  • toYaml / fromYaml / fromYamlArray helm like functions

Examples

Basic Go template usage

This example shows basic string parameter substitution.

  1. apiVersion: argoproj.io/v1alpha1
  2. kind: ApplicationSet
  3. metadata:
  4.   name: guestbook
  5. spec:
  6.   goTemplate: true
  7.   goTemplateOptions: ["missingkey=error"]
  8.   generators:
  9.   - list:
  10.       elements:
  11.       - cluster: engineering-dev
  12.         url: https://1.2.3.4
  13.       - cluster: engineering-prod
  14.         url: https://2.4.6.8
  15.       - cluster: finance-preprod
  16.         url: https://9.8.7.6
  17.   template:
  18.     metadata:
  19.       name: '{{.cluster}}-guestbook'
  20.     spec:
  21.       project: my-project
  22.       source:
  23.         repoURL: https://github.com/infra-team/cluster-deployments.git
  24.         targetRevision: HEAD
  25.         path: guestbook/{{.cluster}}
  26.       destination:
  27.         server: '{{.url}}'
  28.         namespace: guestbook

Fallbacks for unset parameters

For some generators, a parameter of a certain name might not always be populated (for example, with the values generator or the git files generator). In these cases, you can use a Go template to provide a fallback value.

  1. apiVersion: argoproj.io/v1alpha1
  2. kind: ApplicationSet
  3. metadata:
  4.   name: guestbook
  5. spec:
  6.   goTemplate: true
  7.   goTemplateOptions: ["missingkey=error"]
  8.   generators:
  9.   - list:
  10.       elements:
  11.       - cluster: engineering-dev
  12.         url: https://kubernetes.default.svc
  13.       - cluster: engineering-prod
  14.         url: https://kubernetes.default.svc
  15.         nameSuffix: -my-name-suffix
  16.   template:
  17.     metadata:
  18.       name: '{{.cluster}}{{dig "nameSuffix" "" .}}'
  19.     spec:
  20.       project: default
  21.       source:
  22.         repoURL: https://github.com/argoproj/argo-cd.git
  23.         targetRevision: HEAD
  24.         path: applicationset/examples/list-generator/guestbook/{{.cluster}}
  25.       destination:
  26.         server: '{{.url}}'
  27.         namespace: guestbook

This ApplicationSet will produce an Application called engineering-dev and another called engineering-prod-my-name-suffix.

Note that unset parameters are an error, so you need to avoid looking up a property that doesn’t exist. Instead, use template functions like dig to do the lookup with a default. If you prefer to have unset parameters default to zero, you can remove goTemplateOptions: ["missingkey=error"] or set it to goTemplateOptions: ["missingkey=invalid"]